"""
Copyright 2009 Texas A&M University
 
Licensed under the Apache License, Version 2.0 (the "License"); you may not use 
this file except in compliance with the License. You may obtain a copy of the 
License at

http://www.apache.org/licenses/LICENSE-2.0
  
Unless required by applicable law or agreed to in writing, software distributed 
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR 
CONDITIONS OF ANY KIND, either express or implied. See the License for the 
specific language governing permissions and limitations under the License. 
"""

import zope.interface

class IResource(zope.interface.Interface):
    """A Resource is a collection of instances.  It does not contain any 
    metadata other than its own unique identifier.
    
    """
    def __len__(self):
        """This method should return the number of instances of this resource
        """
    
    def __iter__(self):
        """Return an object that implements the iterator interface and iterates
        over the instances of this resource
        """
    
    def getIdentifier(self):
        """Return the unique identifier for this resource """

    
    def getMetadata(self):
        """Retrieve the metadata from instances. This should  be an interable 
        container of objects that implement the meercat.interfaces.IMetadata
        interface.
        """

    def getLastModified(self):
        """Retrieve the last modified datetime object for this resource """

    def isActive(self):
        """Iterate over the instances and if any are active, then the resource
        is active
        """
    
class IMutableResource(IResource):
    """A mutable resource can be deactivated, have additional instances added,
    or some of its instances removed
    """
    
    def deactivate(self):
        """Iterate over the instances and mark them all as inactive.  As long 
        as a resource has one active instance, it is active.
        """

    def append(self, instance):
        """Append an instance to the collection of instances for this resource
        """
    
    def remove(self, instance):
        """Remove a given instance from the collection of instances for this
        resource.  Return the removed instance.  Generally, removed instances
        must be appended to another resource before being saved.
        """